Section 3.2.5.4
WHILE Directive

The #while directive is a looping feature that makes it easy to place multiple objects in a pattern or other uses. The #while directive is followed by a float expression that evaluates to a boolean value. A value of 0.0 is false and any non-zero value is true. Note that extremely small values of about 1e-10 are considered zero in case of round off errors. The parentheses around the expression are required. If the condition is true, parsing continues normally until an #end directive is reached. At the end, POV-Ray loops back to #while directive and the condition is re-evaluated. Looping continues until the condition fails. When it fails, parsing continues after the #end directive. For example:

#declare Count=0 #while (Count < 5) object{MyObject translate x*3*Count} #declare Count=Count+1 #end

This example places five copies of MyObject in a row spaced three units apart in the x direction.

Section 3.2.6
User Message Directives

With the addition of conditional and loop directives, the POV-Ray language has the potential to be more like an actual programming language. This means that it will be necessary to have some way to see what is going on when trying to debug loops and conditionals. To fulfill this need we have added the ability to print text messages to the screen. You have a choice of five different text streams to use including the ability to generate a fatal error if you find it necessary. Limited formatting is available for strings output by this method.

Section 3.2.6.1
Text Message Streams

The syntax for a text message is any of the following:

#debug STRING #error STRING #fatal STRING #render STRING #statistics STRING #warning STRING

Where STRING is any valid string of text including string identifiers or functions which return strings.

For example:

#switch (clock*360) #range (0,180) #render "Clock in 0 to 180 range\n" #break #range (180,360) #render "Clock in 180 to 360 range\n" #break #else #warning "Clock outside expected range\n" #warning concat("Value is:",str(clock*360,5,0),"\n") #end

There are seven distinct text streams that POV-Ray uses for output. You may output only to five of them. On some versions of POV-Ray, each stream is designated by a particular color. Text from these streams are displayed whenever it is appropriate so there is often an intermixing of the text. The distinction is only important if you choose to turn some of the streams off or to direct some of the streams to text files. On some systems you may be able to review the streams separately in their own scroll-back buffer. See "Console Text Output" for details on re-directing the streams to a text file.

Here is a description of how POV-Ray uses each stream. You may use them for whatever purpose you want except note that use of the #fatal stream causes a fatal error after the text is displayed.

DEBUG: This stream displays debugging messages. It was primarily designed for developers but this and other streams may also be used by the user to display messages from within their scene files.

FATAL: This stream displays fatal error messages. After displaying this text, POV-Ray will terminate. When the error is a scene parsing error, you may be shown several lines of scene text that leads up to the error.

RENDER: This stream displays information about what options you have specified to render the scene. It includes feedback on all of the major options such as scene name, resolution, animation settings, anti-aliasing and others.

STATISTICS: This stream displays statistics after a frame is rendered. It includes information about the number of rays traced, the length of time of the processing and other information.

WARNING: This stream displays warning messages during the parsing of scene files and other warnings. Despite the warning, POV-Ray can continue to render the scene.

The BANNER and STATUS streams can not be accessed by the user.

Section 3.2.6.2
Text Formatting

Some escape sequences are available to include non-printing control characters in your text. These sequences are similar to those used in string literals in the C programming language. Note that these control characters only apply in text message directives. They are not implemented for other string usage in POV-Ray such as text objects or file names. Depending on what platform you are using, they may not be fully supported for console output. However they will appear in any text file if you re-direct a stream to a file. The sequences are:

"\a"	Bell or alarm, 0x07
"\b"	Backspace, 0x08
"\f"	Form feed, 0x0C
"\n"	New line (line feed) 0x0A
"\r"	Carriage return 0x0D
"\t"	Horizontal tab 0x09
"\v"	Vertical tab 0x0B
"\0"	Null 0x00
"\\"	Backslash 0x5C
"\'"	Single quote 0x27

For example:

#debug "This is one line.\nBut this is another"

Section 3.3
POV-Ray Coordinate System

Objects, lights, and the camera are positioned using a typical 3D coordinate system. The usual coordinate system for POV-Ray has the positive Y axis pointing up, the positive X axis pointing to the right, and the positive Z axis pointing into the screen. The negative values of the axes point the other direction, as follows:

The left-handed coordinate system.

Locations within that coordinate system are usually specified by a three component vector. The three values correspond to the x, y and z directions respectively. For example, the vector <1,2,3> means the point that's 1 unit to the right, 2 units up, and 3 units in front the center of the "universe" at <0,0,0>.

Vectors are not always points, though. They can also refer to an amount to size, move, or rotate a scene element or to modify the texture pattern applied to an object.

The supported transformations are rotate, scale, and translate. They are used to turn, size, and translate an object or texture. A transformation matrix may also be used to specify complex transformations directly.

Section 3.3.1
Transformations

The supported transformations are rotate, scale, and translate. They are used to turn, size, and translate an object or texture.

rotate <VECTOR> scale <VECTOR> translate <VECTOR>

Section 3.3.1.1
Translate

An object or texture pattern may be moved by adding a translate parameter. It consists of the keyword translate followed by a vector expression. The terms of the vector specify the number of units to move in each of the x, y, and z directions. Translate moves the element relative to it's current position. For example

sphere { <10, 10, 10>, 1 pigment { Green } translate <-5, 2, 1> }

Will move the sphere from <10,10,10> to <-5,12,11>. It does not move it to absolute location <-5,2,1>. Translating by zero will leave the element unchanged on that axis. For example:

sphere { <10, 10, 10>, 1 pigment { Green } translate 3*x // evaluates to <3,0,0> so move 3 units // in the x direction and none along y or z }

Section 3.3.1.2
Scale

You may change the size of an object or texture pattern by adding a scale parameter. It consists of the keyword scale followed by a vector expression. The 3 terms of the vector specify the amount of scaling in each of the x, y, and z directions.

Scale, is used to "stretch" or "squish" an element. Values larger than 1 stretch the element on that axis. Values smaller than one are used to squish the element on that axis. Scale is relative to the current element size. If the element has been previously re-sized using scale, then scale will size relative to the new size. Multiple scale values may used.

For example:

sphere { <0,0,0>, 1 scale <2,1,0.5> }

This stretches and smashes the sphere into an ellipsoid shape that is twice the original size along the x direction, remains the same size in the y direction, and is half the original size in the z direction.

If a lone float expression is specified, it is promoted to a 3 component vector whose terms are all the same. Thus the item is uniformly scaled by the same amount in all directions. For example:

object { MyObject scale 5 // Evaluates as <5,5,5> so uniformly scale // by 5 in every direction. }

Section 3.3.1.3
Rotate

You may change the orientation of an object or texture pattern by adding a rotate parameter. It consists of the keyword rotate followed by a vector expression. The three terms of the vector specify the number of degrees to rotate about each of the x, y, and z axes.

Note that the order of the rotations does matter. Rotations occur about the x axis first, then the y axis, then the z axis. If you are not sure if this is what you want then you should only rotate on one axis at a time using multiple rotation statements to get a correct rotation. As in,

rotate <0, 30, 0> // 30 degrees around Y axis then, rotate <-20, 0, 0> // -20 degrees around X axis then, rotate <0, 0, 10> // 10 degrees around Z axis.

Rotation is always performed relative to the axis. Thus if an object is some distance from the axis of rotation, its will not only rotate but it will "orbit" about the axis as though it was swinging around on an invisible string.

To work out the rotation directions, you must perform the famous "Computer Graphics Aerobics" exercise. Hold up your left hand. Point your thumb in the positive direction of the axis of rotation. Your fingers will curl in the positive direction of rotation. Similarly if you point your thumb in the negative direction of the axis your fingers will curl in the negative direction of rotation. This is the famous "left-hand coordinate system".

"Computer Graphics Aerobics" to determine the rotation direction.

In this illustration, the left hand is curling around the x axis. The thumb points in the positive x direction and the fingers curl over in the positive rotation direction.

If you want to use a right hand system, as some CAD systems such as AutoCAD do, the right vector in the camera specification needs to be changed. See the detailed description of the camera. In a right handed system you use your right hand for the "Aerobics".

Note: There is some controversy over whether POV-Ray's method of doing a right-handed system is really proper. If you want to avoid problems we suggest you stick with the left-handed system which is not in dispute.

Section 3.3.1.4
Matrix Keyword

The matrix keyword can be used to explicitly specify the transformation matrix to be used for objects or textures. Its syntax is:

matrix < M00, M01, M02, M10, M11, M12, M20, M21, M22, M30, M31, M32 >

Where M00 through M32 are float expressions that specify the elements of a 4x4 matrix with the fourth column implicitly <0,0,0,1>. A point P=<px, py, pz> is transformed into Q=(qx, qy, qz) by

  qx = M00 * px + M10 * py + M20 * pz + M30
  qy = M01 * px + M11 * py + M21 * pz + M31
  qz = M02 * px + M12 * py + M22 * pz + M32

Normally you won't use the matrix keyword because it's less descriptive than the transformation commands and harder to visualize. There is an intersecting aspect of the matrix command though. It allows more general transformation like shearing. The following matrix causes an object to be sheared along the y axis.

object { MyObject matrix < 1, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0 > }

Section 3.3.2
Transformation Order

Because rotations are always relative to the axis and scaling is relative to the origin, you will generally want to create an object at the origin and scale and rotate it first. Then you may translate it into its proper position. It is a common mistake to carefully position an object and then to decide to rotate it. Because a rotation of an object causes it to orbit the axis, the position of the object may change so much that it orbits out of the field of view of the camera!

Similarly scaling after translation also moves an object unexpectedly. Ifyou scale after you translate, the scale will multiply the translate amount. For example:

translate <5, 6, 7> scale 4

Will translate to 20, 24, 28 instead of 5, 6, 7. Be careful when transforming to get the order correct for your purposes.

Section 3.3.3
Transform Identifiers

At times it is useful to combine together several transformations and apply them in multiple places. A transform identifier may be used for this purpose. Transform identifiers are declared as follows:

#declare IDENT=transform { TRANSFORMATION... }

Where IDENT is the identifier to be declared and TRANSFORMATION is one or more translate, rotate, scale or matrix specifications or a previously declared transform identifier. A transform identifier is invoked by the transform keyword without any brackets as shown here:

object { MyObject // Get a copy of MyObject transform MyTrans // Apply the transformation translate -x*5 // Then move it 5 units left } object { MyObject // Get another copy of MyObject transform MyTrans // Apply the same transformation translate -x*5 // Then move this one 5 units right }

On extremely complex CSG objects with lots of components, it may speed up parsing if you apply a declared transformation rather than the individual translate, rotate, scale or matrix specifications. The transform is attached just once to each component. Applying each individual translate, rotate, scale or matrix specifications takes long. This only affects parsing --- rendering works the same either way.

Section 3.3.4
Transforming Textures and Objects

When an object is transformed, all textures attached to the object at that time are transformed as well. This means that if you have a translate, rotate, scale or matrix in an object before a texture, the texture will not be transformed. If the transformation is after the texture then the texture will be transformed with the object. If the transformation is inside the texture {...} statement then only the texture is affected. The shape remains the same. For example:

sphere { 0, 1 texture { Jade } // texture identifier from TEXTURES.INC scale 3 // this scale affects both the // shape and texture } sphere { 0, 1 scale 3 // this scale affects the shape only texture { Jade } } sphere { 0, 1 texture { Jade scale 3 // this scale affects the texture only } }

Transformations may also be independently applied to pigment patterns and surface normal (bump) patterns. Note scaling a normal pattern affects only the width and spacing. It does not affect the apparent height or depth of the bumps. For example:

box { <0, 0, 0>, <1, 1, 1> texture { pigment { checker Red, White scale 0.25 // This affects only the color pattern } normal { bumps 0.3 // This specifies apparent height of bumps scale 0.2 // Scales diameter and space between bumps // but not the height. Has no effect on // color pattern. } rotate y*45 // This affects the entire texture but } // not the object. }

Next Section
Table Of Contents